Cream of the Crop 1/Cream of the Crop 1.iso/EDUCATE/SNDPPR3.ARJ/SANDPAPR.DOC

Text File | 1992-02-06 | 10KB | 217 lines

Sandpaper
4/26/91
Mike Schoenborn

Sandpaper is a simple little utility that reads in triangle data, then
outputs that same triangle data with surface normals appended.  This
"polygon patch" or "smooth triangle" output can be used with a raytracing
program to produce smooth looking surfaces, instead of the flat "faceted"
look you get with triangles alone.  Consider the difference between a
geodesic dome and a smooth sphere, and you'll have the idea. (I've included
a tiny, simple GIF file as an example).

The input data should consist of numbers only, seperated by whitespace,
in groups of 9; three numbers (x,y,z) per point, and three points per
triangle.  Any other text _must_ be editted out ahead of time, or you'll
get truncated, nonsense results. "Whitespace" simply means spaces, tabs,
carriage returns, etc., so it's pretty flexible.

This... 1.0  2.0  3.0
        4.0  5.0  6.0
        7.0  8.0  9.0   works just as well as...

1 2 3 4 5 6 7 8 9       which works as well as...

1.0 2.0000
        3 4

 5.  0006.0

7.000 8e-0  9

The input routine is pretty forgiving, but I haven't really tried hard
to break it.  Numbers only, in groups of nine.  (If the number of triangles
coming out is the same as the number that went in, then things worked ok).


Several output formats are available via a command line switch; currently:

        -n : NFF (MTV)
        -v : Vivid
        -d : DKBTrace (STAR)
        -r : Rayshade

An example of each of these formats is given in the accompanying Sample.Doc.
If no command line format option is specified, the output will be in "raw"
form; just the triangles and normals without any other text.

(Note: "SMOOTH_TRIANGLES" in the current (2.10) version of DKBTrace don't
work.  It's not this program, honest).

There are a few other command line switches available:

-q : Normally the program will display a count on the screen as the
     triangles are read in.  This switch turns off the output.

-z : This will send debugging info to the output.  Unless you're poking
     around in the source code, this probably won't be very interesting.

-h : These (or any unrecognized switches, for that matter) just show
-? : brief usage instructions, "help".

An option may be given in upper or lower case, and is preceeded with a dash,
forward slashe or backslashe.  Options may be grouped, as in "-rqz".


Unlike programs that require named input and output files, this program acts
as a "filter".  That is, it reads input data from the "standard input" (by
default, the keyboard) and sends the results to the "standard output" (by
default, the screen).  This may be familiar to those that are accustomed to
working with "pipes", but for others, here's a simple example:

        C:\TRACERS\>type input.raw | sp -d > tri.dat

This will take raw triangle data from the file "input.raw", "pipe" it through
the Sandpaper "filter" utility, then put the output into the file "tri.dat".
(If the "tri.dat" file already existed, it would be overwritten).

If you're unfamiliar with how this works, and are curious enough to find out,
see a DOS manual (the "more" and "sort" commands work the same way).
Otherwise just do it like the example and forget about it.

Caution: If you just type "sp <cr>", nothing will seem to happen.  What
it's doing it waiting for something to come in from the "standard input"
which, in this case, would be your keyboard.  Actually, you *could* go ahead
and type in the data by hand, but that's entirely up to you.


Memory Considerations ---

Sorry, it's impossible to say (simply) exactly how much memory is required
to run this program.  The memory requirements are determined by the number of
triangles and number of points, obviously, but also by how the triangles are
arranged, the number of points which are unique, which points belong to which
triangles...

Consider these two figures...
           _______                  _____________________________________
         / \     / \               / \         / \         / \         /
       /    \   /    \           /     \     /     \     /     \     /
     /_______\/________\       /         \ /         \ /         \ /
     \       /\       /       -------------------------------------
       \    /   \    /
         \/_______\/

6 triangles                             6 triangles
7 unique points                         8 unique points
6 points belong to only 2 tri's         2 points belong to only 1 tri
1 point belongs to 6 tri's              2 points belong to 2 tri's
                                        4 points belong to 3 tri's

Since the program doesn't know how the input triangles are going to be
arranged, it can't plan ahead of time on how to balance the memory allocation
for the triangles, points, and (most awkwardly) the "belongs to" information.
I suppose it could have been written to use some arbitrarily huge tables based
on some arbitrarily presumptuous assumptions...but it wasn't.  Instead, it uses
a linked list way of doing things, and seems to work.  Complain if you must,
but back it up with new source code.

I've sent a data set of more than 700 triangles through and the program had
no problem with it.  It will definately handle a lot, but you just can't be
exact as to how much "a lot" actually is.  If it does run out of memory, it
will abort with a message saying how much it did handle before choking.
(The data, btw, was from Marco Reinig's mods to FractInt...the result was a
delightfully smooth, almost "melted" looking, Mt.Mandlebrot :-).

If you do run out of memory, you have a couple of options.  One is to modify
the source for large model, far pointers, etc.  Another, probably better
idea, is to split up the data into multiple groups and process each group
seperately.  If you go this route, consider the layout of your data and keep
in mind that the normals are calculated based on adjoining triangles only.
You could split your data, allowing a 1 triangle overlap at the split, process
each group, then remove the overlap duplicate data when you recombine the
outputs.

Errors Messages ---

This program is really so simple its hard to screw things up.

If you specify more than one output format switch, it will gripe and abort.

If it runs out of memory, it will tell you so, and abort.

If you ignore the input formatting rules (such as they are) it will punish
you by going ahead to produce output that is all wrong (but attractively
formated) and allow you to waste precious time raytracing with it.
Garbage in, garbage out.


********************** DISCLAIMERS, COPYRIGHT, ETC ************************

                                <none>

Or, as a friend once said "You break it, you bought it". (This is the
same fellow, btw, that once told me: "Any jumbo, sufficiently large, is
indistinguishable from mumbo"...so, consider the source).  If this breaks
something its not suppose to, I'm very sorry, but not liable.  Whaddya want,
I'm giving you the source code, for crying out loud.  And if you want
something official, here it is: "This program is public domain".  Sheesh.


Enhancements ---

None planned, but I'm open to suggestions.  A few things that might be
nice would be:

        Support for additional tracer formats as the need arises (this
        is *real* simple to implement).

        Allowing "-i" and "-o" options to specify input and output file
        names for those uncomfortable with piping.

        Rework the code for far pointers and large model.  I started
        on this but things began to break, so I backed off.

        The ability to take an existing tracer input file, process whatever
        triangles are there, and fold the results back into the original.

        An alternate name for the program that isn't so _damn_ cute.

        Some optimization for speed or size.  I really made no attempt to
        optimize this, at the source level nor at compile time.  There are
        plenty of places where a variable is filled in one statement, then
        tested seperately in the next.  Big deal, the source is readable.
        I'm sure there are cpu-state counters that would like to see every
        last bit of performance wringed out of this, but it runs plenty
        fast for me and I have better things to get into.

        Docs suggesting ways of generating raw triangles in the first place.


I hope you like it,

Mike Schoenborn
CIS: [70010,147] COMART Forum/Raytrace Section
(or somewhat less reliably: [e-mail])


Change List

10/28/91        Function end_of_list() didn't check for being passed a
                NULL pointer.  This has been fixed and the program now
                compiles cleanly with all memory models.  The sp.exe
                executable was compiled with the compact memory model
                which should allow quite large data sets to be processed.
                The Vivid output format has also been changed to conform
                to version 2.0.                 Stephen Coy
                                                70413,136
                                                [e-mail]


1/20/92         Added Vivid 1.0(-o commandline) and PoV output(-p).  PoV is
                the same as DKB only lowercase.
                                                Steven Cox
                                                The Graphics Alternative
                                                [phone]
/* eof */